Skip to content

Keep the verifier's hash algorithms for every transaction type. - #2186

Merged
davidz25 merged 1 commit into
openwallet-foundation:mainfrom
TheBlackBit:fix/transaction-data-hashes-alg
Nov 20, 2026
Merged

davidz25 merged 1 commit into
openwallet-foundation:mainfrom
TheBlackBit:fix/transaction-data-hashes-alg

Conversation

@TheBlackBit

@TheBlackBit TheBlackBit commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #2214

Split out of #2178. Related to #2010.

Summary

TransactionType.parseJson() dropped transaction_data_hashes_alg. A transaction type that doesn't override it hashed its transaction data with SHA-256 even when the verifier asked for another algorithm. PaymentTransaction and PingTransaction read the list in their own parseJson(), so they weren't affected.

The base function now reads it the same way. A value that isn't an array of strings is refused.

Testing

  • :multipaz:jvmTest (with the new TransactionTypeParseJsonTest), :multipaz-doctypes:jvmTest and detektMetadataCommonMain, run separately.

  • The mixed-array case fails if the per-element type check is removed.

  • Tests pass

  • Appropriate changes to README are included in PR (none needed)

@TheBlackBit
TheBlackBit marked this pull request as draft November 12, 2026 13:20
@TheBlackBit
TheBlackBit requested a review from dzuluaga November 12, 2026 13:20
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 12, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType` and `sdJwtKbType()` give the `typ` header
    the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
    `kb+jwt`. A type decides it over all of its items at once, since one
    KB-JWT signs them all, so the result does not depend on their order.
    `TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
    refuses two types that ask for different values.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` and the
    ISO/IEC 18013-5 SD-JWT path present with the new
    `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
    `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
    passes the `typ` header.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 by default), and always names that algorithm in
    `_sd_alg`;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown; `shownMandates()` gives the filled-in
    mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
    mandates names a further key in `cnf`.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1717 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.1 and SwiftBridge
needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@TheBlackBit TheBlackBit moved this to In review in CredentAgent Nov 13, 2026
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 14, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType` and `sdJwtKbType()` give the `typ` header
    the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
    `kb+jwt`. A type decides it over all of its items at once, since one
    KB-JWT signs them all, so the result does not depend on their order.
    `TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
    refuses two types that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` and the
    ISO/IEC 18013-5 SD-JWT path present with the new
    `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
    `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
    passes the `typ` header.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 by default), and always names that algorithm in
    `_sd_alg`;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown; `shownMandates()` gives the filled-in
    mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
    mandates names a further key in `cnf`.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@dzuluaga dzuluaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fix is right and small. The base parseJson() now keeps transaction_data_hashes_alg, which OpenID4VP 1.0 B.3.3.1 requires the wallet to honour ("the hash function MUST be one of its values"), and every refusal it adds is an IllegalArgumentException, which the wallet already catches at OpenID4VP.kt:450. Ready once the issue link is changed. Reviewed at 863c95b.

What a developer writes. A transaction type that doesn't override parseJson() now writes nothing to have the verifier's list honoured. Before, it needed an 11-line override like PaymentTransaction.parseJson(). No type in the repository reaches this path yet; DelegateTransaction in #2178 will be the first.

Before merge

  1. The first line of the description closes the wrong issue. #2010 is about the unregistered delegate type and the wrapping of KB-JWT claims. It doesn't mention hash algorithms, and this PR changes neither of those. Merging would close it while #2178 and #2196, which do address it, are still open. CONTRIBUTING.md asks for a linked issue with a closing keyword, so: open an issue for the dropped transaction_data_hashes_alg, close that one from here, and mention #2010 without a keyword.

Non-blocking. 6 line comments: 3 suggestions and 3 nits. The one I would take is on the [384] test, which passes with or without the check it is there for.

Scope. One purpose, 24 lines of source. The same change is in #2178 and #2196, so this one should merge first.

Not verified. Nothing was built or run. build_and_test passed on this commit. "4 of the 5 new tests fail without the change" holds by trace only. The 1727 count and the non-JVM targets were not checked.

@dzuluaga dzuluaga moved this from In review to In progress in CredentAgent Nov 14, 2026
@dzuluaga dzuluaga assigned TheBlackBit and unassigned dzuluaga Nov 14, 2026
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 17, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType` and `sdJwtKbType()` give the `typ` header
    the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
    `kb+jwt`. A type decides it over all of its items at once, since one
    KB-JWT signs them all, so the result does not depend on their order.
    `TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
    refuses two types that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` and the
    ISO/IEC 18013-5 SD-JWT path present with the new
    `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
    `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
    passes the `typ` header.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 by default), and always names that algorithm in
    `_sd_alg`;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown; `shownMandates()` gives the filled-in
    mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
    mandates names a further key in `cnf`.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 17, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType` and `sdJwtKbType()` give the `typ` header
    the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
    `kb+jwt`. A type decides it over all of its items at once, since one
    KB-JWT signs them all, so the result does not depend on their order.
    `TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
    refuses two types that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` and the
    ISO/IEC 18013-5 SD-JWT path present with the new
    `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
    `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
    passes the `typ` header.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 by default), and always names that algorithm in
    `_sd_alg`;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown; `shownMandates()` gives the filled-in
    mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
    mandates names a further key in `cnf`.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 17, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType()` gives the `typ` header the Key Binding
    JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
    which `SdJwt.present()` used to hardcode. A type decides it over all of
    its items at once, since one KB-JWT signs them all, so the result does
    not depend on their order. `TransactionData.sdJwtKbType()`, internal,
    combines the types and refuses two that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` presents with
    the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
    as `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
    Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
    The ISO/IEC 18013-5 path only reads the new response type and refuses
    disclosures, which its reader cannot accept.
    `TransactionType.isApplicable()` may now throw
    `IllegalArgumentException` for transaction data that is malformed, and
    `OpenID4VP` reports it with its reason, like a parse failure.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
    Selectively disclosable terms are matched under each mandate's own
    `_sd_alg`, SHA-256 when absent (RFC 9901);
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown, throwing with the reason;
    `shownMandates()` gives the filled-in mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
    mandates names a further key in `cnf`, and requires a `cnf` for the
    `dSD-JWT+KB` format.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`; a closed checkout's
`checkout_jwt` is read for what the merchant signed, and the domain is the
host without any userinfo. Amounts follow AP2's units: `payment.budget` in
major units, other amounts in minor units. `detailsOf()` gives one mandate's
heading, type and lines for a details page. What it recognises by name, the
constraint kinds and their members, the units of each amount, the merchant
and line item members, the mandate types and the date claims, is kept in
tables that a test checks against AP2 v0.2.0's own JSON Schemas, copied
unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (98 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms and closed checkouts that follow AP2's schema, through a full
OpenID4VP presentation, checks the Delegated SD-JWT shape and that a request
missing a disclosure is refused with its reason); ./gradlew :multipaz:jvmTest
(1872 tests, including TransactionDataSdJwtKbTypeTest, the new SdJwtTest cases
and the unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
responses DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0
(b4587ac) through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7
scenarios, with the mandates the SDK resolves matching the requested ones; the
script also checks the nonce and audience, which the SDK skips on an
intermediate hop. iOS targets were not built: this host has Xcode 27.2 and
SwiftBridge needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 17, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType()` gives the `typ` header the Key Binding
    JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
    which `SdJwt.present()` used to hardcode. A type decides it over all of
    its items at once, since one KB-JWT signs them all, so the result does
    not depend on their order. `TransactionData.sdJwtKbType()`, internal,
    combines the types and refuses two that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` presents with
    the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
    as `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
    Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
    The ISO/IEC 18013-5 path only reads the new response type and refuses
    disclosures, which its reader cannot accept.
    `TransactionType.isApplicable()` may now throw
    `IllegalArgumentException` for transaction data that is malformed, and
    `OpenID4VP` reports it with its reason, like a parse failure. Both it
    and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
    `DelegateTransaction` must on Kotlin/Native.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
    Selectively disclosable terms are matched under each mandate's own
    `_sd_alg`, SHA-256 when absent (RFC 9901);
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown, throwing with the reason;
    `shownMandates()` gives the filled-in mandates to a consent screen;
  * types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
    mandates names a further key in `cnf`, and requires a `cnf` for the
    `dSD-JWT+KB` format.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`; a closed checkout's
`checkout_jwt` is read for what the merchant signed, and the domain is the
host without any userinfo. Amounts follow AP2's units: `payment.budget` in
major units, other amounts in minor units. `detailsOf()` gives one mandate's
heading, type and lines for a details page. What it recognises by name, the
constraint kinds and their members, the units of each amount, the merchant
and line item members, the mandate types and the date claims, is kept in
tables that a test checks against AP2 v0.2.0's own JSON Schemas, copied
unchanged into the tests, so a protocol change cannot go unnoticed.

The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.

Test: ./gradlew :multipaz-utopia:jvmTest (98 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms and closed checkouts that follow AP2's schema, through a full
OpenID4VP presentation, checks the Delegated SD-JWT shape and that a request
missing a disclosure is refused with its reason); ./gradlew :multipaz:jvmTest
(1872 tests, including TransactionDataSdJwtKbTypeTest, the new SdJwtTest cases
and the unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
responses DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0
(b4587ac) through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7
scenarios, with the mandates the SDK resolves matching the requested ones; the
script also checks the nonce and audience, which the SDK skips on an
intermediate hop. iOS targets were not built: this host has Xcode 27.2 and
SwiftBridge needs the iOS 27.3 SDK; the iOS simulator targets of multipaz,
multipaz-utopia and multipaz-doctypes, and their tests, do compile.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 18, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType()` gives the `typ` header the Key Binding
    JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
    which `SdJwt.present()` used to hardcode. A type decides it over all of
    its items at once, since one KB-JWT signs them all, so the result does
    not depend on their order. `TransactionData.sdJwtKbType()`, internal,
    combines the types and refuses two that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` presents with
    the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
    as `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
    Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
    The ISO/IEC 18013-5 path only reads the new response type and refuses
    disclosures, which its reader cannot accept.
    `TransactionType.isApplicable()` may now throw
    `IllegalArgumentException` for transaction data that is malformed, and
    `OpenID4VP` reports it with its reason, like a parse failure. Both it
    and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
    `DelegateTransaction` must on Kotlin/Native.
  * `TransactionType.validateTogether()`, which does nothing by default,
    lets a type check, before the consent prompt, the items of one
    credential that a single response answers together, so a request that
    could only fail after the person approved is refused up front with its
    reason. `OpenID4VP` calls it when it parses `transaction_data`.
  * `TransactionType.requiresRenderer`, default `false`. A type that sets it
    cannot be approved with the built-in rendering: `PromptModel
    .requestConsent()` throws `TransactionDataRendererNotAvailableException`,
    naming the type, when no renderer is registered for it or no repository
    was passed, and the Compose and SwiftUI consent dialogs refuse the same
    way when the renderer registered is made for the other toolkit.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
    The terms selectively disclosable within a mandate are resolved with
    that same algorithm, because AP2's verifier hashes every nested digest
    with the KB-JWT's and drops what does not match; a mandate that names
    another `_sd_alg` is refused;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown, throwing with the reason. A `cnf` behind a
    digest, a key it cannot show, and a closed checkout whose
    `checkout_hash` is not the hash of its `checkout_jwt` are refused too.
    Items that settle on different algorithms, or share a disclosure, are
    refused together before the prompt;
  * types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
    mandates names a further key in `cnf`, and requires a `cnf` for the
    `dSD-JWT+KB` format;
  * sets `requiresRenderer`, because its built-in rendering shows only a
    heading and a person must not approve a spending permission they were
    not shown.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.

`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.

Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2 mandate sets in both request
forms, one with selectively disclosed terms and closed checkouts that follow
the UCP schema, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure, or with items on
different algorithms, is refused with its reason); ./gradlew :multipaz:jvmTest
(1879 tests, one skipped before this change, including
TransactionDataSdJwtKbTypeTest, TransactionDataValidateTogetherTest,
TransactionDataRendererRequirementTest, the new SdJwtTest cases and the
unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
iOS simulator targets of multipaz, multipaz-utopia, multipaz-doctypes and
multipaz-compose, and the iOS tests of the first two, compile. The responses
DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0 (b4587ac)
through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with
the mandates the SDK resolves matching the requested ones; the script also
checks the nonce and audience, which the SDK skips on an intermediate hop,
and is not run in CI. The SwiftUI dialog change was not built: this host has
Xcode 27.2 and SwiftBridge needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 18, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType()` gives the `typ` header the Key Binding
    JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
    which `SdJwt.present()` used to hardcode. A type decides it over all of
    its items at once, since one KB-JWT signs them all, so the result does
    not depend on their order. `TransactionData.sdJwtKbType()`, internal,
    combines the types and refuses two that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` presents with
    the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
    as `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
    Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
    The ISO/IEC 18013-5 path only reads the new response type and refuses
    disclosures, which its reader cannot accept.
    `TransactionType.isApplicable()` may now throw
    `IllegalArgumentException` for transaction data that is malformed, and
    `OpenID4VP` reports it with its reason, like a parse failure. Both it
    and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
    `DelegateTransaction` must on Kotlin/Native.
  * `TransactionType.validateTogether()`, which does nothing by default,
    lets a type check, before the consent prompt, the items of one
    credential that a single response answers together, so a request that
    could only fail after the person approved is refused up front with its
    reason. `OpenID4VP` calls it when it parses `transaction_data`.
  * `TransactionType.requiresRenderer`, default `false`. A type that sets it
    cannot be approved with the built-in rendering: `PromptModel
    .requestConsent()` throws `TransactionDataRendererNotAvailableException`,
    naming the type, when no renderer is registered for it or no repository
    was passed, and the Compose and SwiftUI consent dialogs refuse the same
    way when the renderer registered is made for the other toolkit.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
    The terms selectively disclosable within a mandate are resolved with
    that same algorithm, because AP2's verifier hashes every nested digest
    with the KB-JWT's and drops what does not match; a mandate that names
    another `_sd_alg` is refused;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown, throwing with the reason. A `cnf` behind a
    digest, a key it cannot show, and a closed checkout whose
    `checkout_hash` is not the hash of its `checkout_jwt` are refused too.
    Items that settle on different algorithms, or share a disclosure, are
    refused together before the prompt;
  * types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
    mandates names a further key in `cnf`, and requires a `cnf` for the
    `dSD-JWT+KB` format;
  * sets `requiresRenderer`, because its built-in rendering shows only a
    heading and a person must not approve a spending permission they were
    not shown.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.

`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.

Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2
mandate sets in both request forms, one with selectively disclosed terms and
closed checkouts that follow the UCP schema, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure, or with items on
different algorithms, is refused with its reason); ./gradlew :multipaz:jvmTest
(1879 tests, one skipped before this change, including
TransactionDataSdJwtKbTypeTest, TransactionDataValidateTogetherTest,
TransactionDataRendererRequirementTest, the new SdJwtTest cases and the
unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
iOS simulator targets of multipaz, multipaz-utopia, multipaz-doctypes and
multipaz-compose, and the iOS tests of the first two, compile. The responses
DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0 (b4587ac)
through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with
the mandates the SDK resolves matching the requested ones; the script also
checks the nonce and audience, which the SDK skips on an intermediate hop,
and is not run in CI. The SwiftUI dialog change was not built: this host has
Xcode 27.2 and SwiftBridge needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
TheBlackBit pushed a commit to TheBlackBit/multipaz that referenced this pull request Nov 18, 2026
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.

Core changes, none specific to this protocol:

  * `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
    a type's response claims are merged into the KB-JWT verbatim instead of
    being nested under `kbJwtResponseClaimName`, and arrays accumulate
    across items of the same type rather than the last item overwriting
    the others. `OpenID4VP.processTransactions()` now refuses a type that
    sets one of the Key Binding JWT's own claims (`iat`, `aud`, `nonce`,
    `sd_hash`, `transaction_data_hashes`, `transaction_data_hashes_alg`), a
    claim another type sets, or a value another item of its type sets
    differently, instead of letting one silently replace the other.
  * `TransactionType.sdJwtKbType()` gives the `typ` header the Key Binding
    JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
    which `SdJwt.present()` used to hardcode. A type decides it over all of
    its items at once, since one KB-JWT signs them all, so the result does
    not depend on their order. `TransactionData.sdJwtKbType()`, internal,
    combines the types and refuses two that ask for different values.
    `SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
    a verifier can check a key binding such as `kb+sd-jwt` only when it
    asks for that profile.
  * `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
    together with disclosures that follow the KB-JWT, as
    `SdJwtTransactionResponse`. By default it returns the claims of
    `generateSdJwtResponseClaims()` and no disclosures, so other types are
    unchanged. When any type returns disclosures, `OpenID4VP` presents with
    the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
    as `present()` and returns the Delegated SD-JWT compact serialization
    `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
    Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
    The ISO/IEC 18013-5 path only reads the new response type and refuses
    disclosures, which its reader cannot accept.
    `TransactionType.isApplicable()` may now throw
    `IllegalArgumentException` for transaction data that is malformed, and
    `OpenID4VP` reports it with its reason, like a parse failure. Both it
    and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
    `DelegateTransaction` must on Kotlin/Native.
  * `TransactionType.validateTogether()`, which does nothing by default,
    lets a type check, before the consent prompt, the items of one
    credential that a single response answers together, so a request that
    could only fail after the person approved is refused up front with its
    reason. `OpenID4VP` calls it when it parses `transaction_data`.
  * `TransactionType.requiresRenderer`, default `false`. A type that sets it
    cannot be approved with the built-in rendering: `PromptModel
    .requestConsent()` throws `TransactionDataRendererNotAvailableException`,
    naming the type, when no renderer is registered for it or no repository
    was passed, and the Compose and SwiftUI consent dialogs refuse the same
    way when the renderer registered is made for the other toolkit.
  * Transaction data parsed from OpenID4VP now keeps
    `transaction_data_hashes_alg`, so a request asking for SHA-384 is no
    longer answered in SHA-256, and a value that is not an array of strings
    is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
    this commit once that is merged.

`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:

  * applies only to key-bound SD-JWT VC credentials and refuses mandates it
    cannot show;
  * accepts both request forms, since the documents disagree: section 7.1's
    `delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
    and AP2's `delegate_payload`, several mandates in the clear with a
    `dc+sd-jwt` format, for which it makes each disclosure with a fresh
    128-bit salt;
  * puts the digest of each mandate's disclosure in the `delegate_payload`
    KB-JWT claim, under the algorithm the request names for the transaction
    data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
    The terms selectively disclosable within a mandate are resolved with
    that same algorithm, because AP2's verifier hashes every nested digest
    with the KB-JWT's and drops what does not match; a mandate that names
    another `_sd_alg` is refused;
  * returns the mandate disclosures, and any `delegate_disclosures` the
    request carried, after the KB-JWT, so a verifier resolves the mandates
    from the presentation itself;
  * fills in the mandates' selectively disclosable terms from
    `delegate_disclosures` and, before the consent prompt, refuses a request
    whose digests and disclosures do not match one to one, so nothing is
    signed that cannot be shown, throwing with the reason. A `cnf` behind a
    digest, a key it cannot show, and a closed checkout whose
    `checkout_hash` is not the hash of its `checkout_jwt` are refused too.
    Items that settle on different algorithms, or share a disclosure, are
    refused together before the prompt;
  * types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
    mandates names a further key in `cnf`, and requires a `cnf` for the
    `dSD-JWT+KB` format;
  * sets `requiresRenderer`, because its built-in rendering shows only a
    heading and a person must not approve a spending permission they were
    not shown.

The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.

`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.

Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2
mandate sets in both request forms, one with selectively disclosed terms and
closed checkouts that follow the UCP schema, through a full OpenID4VP
presentation, checks the Delegated SD-JWT shape and that a request missing a
disclosure, or with items on different algorithms, is refused with its
reason); ./gradlew :multipaz:jvmTest (1879 tests, one skipped before this
change, including TransactionDataSdJwtKbTypeTest,
TransactionDataValidateTogetherTest, TransactionDataRendererRequirementTest,
the new SdJwtTest cases and the unnested array, claim collision and KB
disclosure cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The iOS simulator targets of multipaz,
multipaz-utopia, multipaz-doctypes and multipaz-compose, and the iOS tests of
the first two, compile. The responses DelegateAp2InteropTest exports verify
with AP2's Python SDK v0.2.0 (b4587ac) through
multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with the
mandates the SDK resolves matching the requested ones; the script also checks
the nonce and audience, which the SDK skips on an intermediate hop, and is not
run in CI. The SwiftUI dialog change was not built: this host has Xcode 27.2
and SwiftBridge needs the iOS 27.3 SDK.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
`TransactionType.parseJson()` read the payload of an OpenID4VP
`transaction_data` item but not its `transaction_data_hashes_alg`, so
`TransactionData.hashAlgorithms` was always null for a type that does not
override it. Such a type hashed the item with SHA-256 even when the verifier
asked for another algorithm, and the verifier could not match the hash.
`PaymentTransaction` and `PingTransaction` read the list in their own
`parseJson()`, so they were not affected.

The base `parseJson()` now reads the list with `parseJoseHashAlgorithms()`,
as those overrides do: unknown names are skipped and a list naming no known
algorithm is refused. A value that is not an array of strings is refused as
well, with a message naming `transaction_data_hashes_alg`, instead of being
answered in SHA-256. An absent or null value leaves the default.

Test: ./gradlew :multipaz:jvmTest, :multipaz-doctypes:jvmTest and
detektMetadataCommonMain, run as separate invocations. The new
`TransactionTypeParseJsonTest` covers the round trip, absent and null
values, unknown and unsupported names, and malformed values, including a
number next to a valid name. That last case fails if the per-element type
check in `parseJson()` is removed.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
@TheBlackBit

Copy link
Copy Markdown
Contributor Author

@dzuluaga all threads are addressed in 6a49d21, and CI is green.

Issue link: the PR now closes openwallet-foundation/multipaz#2214, and #2010 is only mentioned.
Test: added the mixed-array case [384, "sha-256"]. It fails when the element check is removed.
Error message: a non-array transaction_data_hashes_alg now names the field.
KDoc: it now says absent or null leaves the default.
@throws: left off, to stay consistent with the file.
Follow-ups: openwallet-foundation/multipaz#2216 removes the duplicated overrides, and openwallet-foundation/multipaz#2215 covers the mismatch check. The mismatch is also reachable today through PaymentTransaction and PingTransaction, so the issue says so.

@dzuluaga dzuluaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, all six threads are addressed in 6a49d21, and the interdiff is only what was asked. The mixed-array test now pins the element check. Fine to leave @Throws off, consistent with the file. #2215 and #2216 cover the follow-ups. LGTM.

@dzuluaga dzuluaga removed their assignment Nov 19, 2026
@TheBlackBit
TheBlackBit marked this pull request as ready for review November 20, 2026 01:08
@TheBlackBit
TheBlackBit requested a review from davidz25 November 20, 2026 01:08

@davidz25 davidz25 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks

@davidz25
davidz25 merged commit 9158014 into openwallet-foundation:main Nov 20, 2026
6 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in CredentAgent Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TransactionType.parseJson() drops transaction_data_hashes_alg

3 participants